<html>
<head>
<title>GRASS</title>
</head>

<body bgcolor="#ffffff">

<h1>GRASS</h1>

GRASS driver can read GRASS (version 6.0 and higher) vector maps.
Each GRASS vector map is represented as one datasource. 
A GRASS vector map may have 0, 1 or more layers. 
<P>
GRASS points are represented as wkbPoint, lines and boundaries
as wkbLineString and areas as wkbPolygon. wkbMulti* and
wkbGeometryCollection are not used.
More feature types can be mixed in one layer. If a layer contains 
only features of one type, it is set appropriately and can be retrieved 
by OGRLayer::GetLayerDefn();
<P>
If a geometry has more categories of the same layer attached, its 
represented as more features (one for each category).
<P>
Both 2D and 3D maps are supported.

<h2>Datasource name</h2>
Datasource name is full path to 'head' file in GRASS vector directory.
Using names of GRASS enviroment variables it can be expressed:
<PRE>
   $GISDBASE/$LOCATION_NAME/$MAPSET/vector/mymap/head
</PRE>
where 'mymap' is name of a vector map. For example:
<PRE>
   /home/cimrman/grass_data/jizerky/jara/vector/liptakov/head
</PRE>

<h2>Layer names</h2>
Usualy layer numbers are used as layer names. Layer number 0 is 
used for all features without any category. It is possible to 
optionaly give names to GRASS layers linked to database 
however currently this is not supported by grass modules.
A layer name can be added in 'dbln' vector file as '/name'
after layer number, for example to original record:
<PRE>
1 rivers cat $GISDBASE/$LOCATION_NAME/$MAPSET/dbf/ dbf
</PRE>
it is possible to assign name 'rivers'
<PRE>
1/rivers rivers cat $GISDBASE/$LOCATION_NAME/$MAPSET/dbf/ dbf
</PRE>
the layer 1 will be listed is layer 'rivers'.

<h2>Attribute filter</h2>
If a layer has attributes stored in a database, the query is passed 
to the underlaying database driver. That means, that SQL conditions
which can be used depend on the driver and database to which the layer 
is linked. For example, DBF driver has currently very limited 
set of SQL expressions and PostgreSQL offeres very rich set of 
SQL expressions.
<p>
If a layer has no attributes linked and it has only categories,
OGR internal SQL engine is used to evaluate the expression.
Category is an integer number attached to geometry, it is sort of ID,
but it is not FID as more features in one layer can have the same category.
<P>
Evaluation is done once when the attribute filter is set.

<h2>Spatial filter</h2>
Bounding boxes of features stored in topology structure are used 
to evaluate if a features matches current spatial filter.
<P>
Evaluation is done once when the spatial filter is set.

<h2>GISBASE</h2>
GISBASE is full path to the directory where GRASS is installed.
By default, GRASS driver is using the path given to gdal configure script.
A different directory can be forced by setting GISBASE enviroment variable.
GISBASE is used to find GRASS database drivers.

<h2>Missing topology</h2>
GRASS driver can read GRASS vector files if topology is available (AKA level 2).
If an error is reported, telling that the topology is not available, it is necessary
to build topology within GRASS using v.build module.

<h2>Random access</h2>
If random access (GetFeature instead of GetNextFeature) is used on layer 
with attributes, the reading of features can be quite slow. It is because the driver 
has to query attributes by category for each feature (to avoid using a lot of memory)
and random access to database is usually slow. This can be improved on GRASS
side optimizing/writing file based (DBF,SQLite) drivers.

<h2>Known problem</h2>
Because of bug in GRASS library, it is impossible to start/stop database
drivers in FIFO order and FILO order must be used. The GRASS driver for OGR
is written with this limit in mind and drivers are always closed if not used 
and if a driver remains opened kill() is used to terminate it.
It can happen however in rare cases, that the driver will try to stop
database driver which is not the last opened and an application hangs.
This can happen if sequential read (GetNextFeature) of a layer is not 
finished (reading is stopped before last available feature is reached),
features from another layer are read and then the reading of the first layer 
is finished, because in that case kill() is not used.

<h2>See Also</h2>
<ul>
<li> <a href="http://grass.itc.it">GRASS home page</a><p>
</ul>

<HR>
Development of this driver was financially supported by Faunalia 
(<a href="http://www.faunalia.it/">www.faunalia.it</a>).


</body>
</html>
